Preface

Creole (aka WikiCreole) is a lightweight markup language, aimed at being a common markup language for wikis. Creole was designed by comparing major wiki engines and using the most common markup for a particular wikitext element. Version 1.0 (final) of Creole was released on 4 July 2007. Link: Creole 1.0 Homepage.

This page describes the syntax of Creole as it is implemented in the Perl module Text::WikiCreole.
Txt2Site uses this module to convert Creole to XHTML and to implement plugins.
This page is completely written with Creole. See the source if you are curious as how it is done.

      Table of content

1. Preface
2. Inline elements Creole 1.0
3. Headings
4. Links
5. Paragraphs
6. Line breaks
7. Lists
1. Unordered Lists
2. Ordered Lists
8. Tables
9. Horizontal Rule
10. Images
11. Nowiki
1. Block Nowiki
2. Inline Nowiki
12. Escape Characters
13. Using HTML
14. Additions to Creole 1.0
1. Additional inline elements
2. Indented paragraphs
3. Definition Lists
4. Plugins

      Inline elements Creole 1.0

Creole	What you see	HTML code
//italics//	italics	<em> italics </em>
**bold**	bold	<strong> bold </strong>
Link to [[Wikipage]]	Link to Wikipage	Link to <a href="Wikipage"> Wikipage </a>
[[ URL | Linkname ]]	Linkname	<a href="URL"> Linkname </a>
No Linebreak! Use empty line	No Linebreak! Use empty line	No Linebreak! <br /> <br /> Use empty line <br />
Force \\\ Linebreak	Force Linebreak	Force <br /> Linebreak
{{ ${path_to_root}include/images/canstock1.jpg | Lion }}		<img src="include/images/canstock1.jpg" alt="Lion" />

      Headings

Headings begin with a equal sign = at the beginning of a line. Closing (right-side) equal signs are optional, don't need to be balanced and don't impact the kind of heading generated. Whitespace is allowed before the left-side equal signs. Only whitespace characters are permitted after the closing equal signs. Markup parsing is done within headings.

What you type:

= Level 1 (largest) =
== Level 2 ==
=== Level 3 ===
==== Level 4 ====
===== Level 5 =====
====== Level 6 ======
=== Also level 3
=== Also level 3 =
=== Also level 3 ==
=== //Italic// heading ===

What you see:

HTML code:

<h1>Level 1 (largest)</h1>
<h2>Level 2</h2>
<h3>Level 3</h3>
<h4>Level 4</h4>
<h5>Level 5</h5>
<h6>Level 6</h6>
<h3>Also level 3</h3>
<h3>Also level 3</h3>
<h3>Also level 3</h3>
<h3> //Italic// heading </h3>

      Links

Links can appear in paragraphs (also inside bold and italic text), list items and table cells. The links are bold or italic if they are part of bold or italic text. Images inside links are supported. Link titles are parsed for other markup within a link.

What you type:

[[#anchorname]]
[[#anchorname | Go to Anchor]]
[[MyBigPage | Go to my page]]
[[http://www.wikicreole.org/]]
http://www.wikicreole.org/
[[http://www.wikicreole.org/ | Visit the WikiCreole website]]
[[New_Stuff_Page | **New** //Stuff//]]
Image link: [[MyBigPage | {{ ${path_to_root}include/images/smiley.gif | Smiley }} ]]

What you see:

HTML code:

<a href="#anchorname">#link</a>
<a href="#anchorname"> Go to Anchor</a>
<a href="MyBigPage">Go to my page</a>
<a href="http://www.wikicreole.org">http://www.wikicreole.org</a>
<a href="http://www.wikicreole.org">http://www.wikicreole.org</a>
<a href="http://www.wikicreole.org">Visit the WikiCreole website</a>
<a href="New_Stuff_Page"><strong>New</strong> <em>Stuff</em></a>
Image link: <a href="MyBigPage"><img src="include/images/smiley.gif" alt="Smiley" /></a>

      Paragraphs

One or more blank lines end paragraphs. A list, table or nowiki block end paragraphs too.

What you type:

This is my text.

This is more text.

What you see:

HTML code:

<p>This is my text.</p>

<p>This is more text.</p>

      Line breaks

Line breaks can be forced by typing three backslashes: \\\ .
The Creole specifications prescribes two backslashes. Because Txt2Site uses the backslash as an escape character, the line break is forced by typing three backslashes. See section Escape Characters.

What you type:

This is the first line,\\\and this is the second.

What you see:

HTML code:

This is the first line,<br />
and this is the second.

      Lists

List items begin with a * or a # at the beginning of a line. Whitespace is optional before and after the * or # characters, however a space is required afterwards if the list element starts with bold text.
A list item ends at the line which begins with a * or a # character (next item or sublist), blank line, heading, table, or nowiki block; like paragraphs, it can span multiple lines and contain line breaks forced with \\\.
Bold, italics, links, and nowiki can be used in list items, but they cannot span several list items.

Unordered Lists

About unordered lists and bold

A line starting with ** (including optional whitespace before and afterwards), immediately following any list element on a line above, will be treated as a nested unordered list element. Otherwise it will be treated as the beginning of bold text.

What you type:

* Item 1
** Item 1.1
** Item 1.2
* Item 2

What you see:

HTML code:

<ul>
    <li>Item 1</li>
<ul>
    <li>Item 1.1</li>
    <li>Item 1.2</li>
</ul>
    <li>Item 2</li>
</ul>

Ordered Lists

What you type:

# Item 1
## Item 1.1
## Item 1.2
# Item 2

What you see:

HTML code:

<ol>
    <li>Item 1</li>
<ol>
    <li>Item 1.1</li>
    <li>Item 1.2</li>
</ol>
    <li>Item 2</li>
</ol>

      Horizontal Rule

A horizontal rule is created by at least four hyphens. Whitespace is optional before and after the hyphens, but no whitespace is allowed between them. The four hyphens must be the only characters (other than whitespace) on that line.

What you type:

---- 

What you see:

HTML code:

<hr /> 

      Images

What you type:

{{${path_to_root}include/images/canstock1.jpg | lion image}} 

What you see:

HTML code:

<img src="include/images/canstock1.jpg" alt="lion image" /> 

      Tables

All cells are separated by single pipes (|). Leading spaces are permitted before the first cell of a row and trailing spaces are permitted at the end of a line. The ending pipe is optional. You can embed links, bold, italics, line breaks, images and nowiki in table cells.
Equal sign directly following pipe (|=) defines a header. Headers can be arranged horizontally or vertically.

What you type:

|= Heading Col 1  |= Heading Col 2          |
| Cell 1.1        | Two lines\\in Cell 1.2  |
| Cell 2.1        | Cell 2.2                |

What you see:

HTML code:

<table class="table_creole" >
    <tr>
        <th>Heading Col 1</th>
        <th>Heading Col 2</th>
    </tr>
    <tr>
        <td>Cell 1.1</td>
        <td>Two lines<br />in Cell 1.2</td>
    </tr>
    <tr>
        <td>Cell 2.1</td>
        <td>Cell 2.2</td>
    </tr>
</table>

      Nowiki

Display lines of preformatted text. This works inline or as a block. No Creole markup is interpreted between these characters, even tildes which are used as escape characters (see section Escape Characters ). However the backslash escape character (\) of Txt2Site applies also to nowiki text.
As a block, the three curly braces should be on one line by itself to open and another line of three curly braces should be on a line by itself to close, without leading spaces.

      Block nowiki

A. What you type:

{{{
//This// does **not** get [[formatted]] 
Type \${page_title} to display the page_title
~}}}

A. What you see:

//This// does **not** get [[formatted]] 
Type ${page_title} to display the page_title

A. HTML code:

<pre>
//This// does **not** get [[formatted]] 
Type ${page_title} to display the page_title
</pre>

      Inline nowiki

B. What you type:

Some examples of markup are: {{{** <i>this</i> ** ~}}}

B. What you see:

B. HTML code:

Some examples of markup are: <span>** &lt;i&gt;this&lt;/i&gt; **</span>

Closing braces in nowiki

To include closing braces where they might be considered as nowiki or preformatted end tag, there are two additional rules:

• In inline nowiki, any trailing closing brace is included in the nowiki span (i.e. in a sequence of more than three closing braces, the end marker is made of the last three braces).
• In preformatted blocks, since markers must not be preceded by leading spaces, lines with three closing braces which belong to the preformatted block must follow at least one space. In the rendered output, one leading space is removed.

Examples:

Inline nowiki with closing braces:

C. What you type:

{{{ {{if (a>b) { b = a; }} }}} 

C. What you see:

Preformatted block with a line containing three closing braces:

D. What you type:

{{{
if (x != NULL) {
  for (i = 0; i < size; i++) {
    if (x[i] > 0) {
      x[i]--;
  }}}

}}}

D. What you see:

if (x != NULL) {
  for (i = 0; i < size; i++) {
    if (x[i] > 0) {
      x[i]--;
  }}}

      Escape Characters

The role of escape characters can be explained by considering the way the text is parsed. Parsing of content sections is carried out in two steps.

1. The evaluation step by Txt2Site.

This step is optional and is carried out if the evaluation flag of the html_content_div function has the value 'eval'. The rules for escaping in this step is determined by bash. The escape character is the backslash (\). In short, it is important to know:

• Evaluation of the ${variable} and $(function) constructs can be prevented if they are preceded by one backslash.
• The Creole specifications prescribes two backslashes for a forced linebreak. Type three backslashes to display two backslashes. If the evaluation step is skipped, only two backslashes for linebreaks are needed.

2. The parsing step by the Creole converter.

This step is processed by the converter which translates Creole syntax to XHTML syntax. The Creole specifications prescribes the tilde (~) as the escape character. Rules for escaping are:

• Outside inline nowiki text, block nowiki lines and URL-strings, the escape character only escapes the character immediately following it, provided that it is not a blank (space or line feed). The following character is rendered as is and cannot be a part of any Creole markup.
• The escape character disables the automatic conversion of the URL-string immediately following to links, and any similar mechanism supported by the converter (bold _etc.)
• Stars, slashes and other markup characters, when found in the original text, can be easily escaped to be rendered as themselves.

A. What you type:

#list item1                   \\\ 
#list item2                   \\\ 

~#list item1                  \\\ 
~#list item2                  \\\ 

A. What you see:

B. What you type:

use the escape character to stop  \\\ 
~{{{                     \\\ 
nowiki blocks from being \\\ 
nowiki blocks            \\\ 
~}}}

B. What you see:

Examples how to use the tilde:

      Using HTML

It is not forbidden to use HTML code within Creole text. But the code is treated as normal Creole text. Mostly the HTML code runs well, but it is not unimaginable that occasionally the code causes unpredictable results or does not meet the W3C web standards.
A plugin is available to insert HTML code in a save way.
The syntax of the plugin is: <<< HTML <lines of code> >>> . The plugin can be used inline or as a block. See the plugin section for more info about plugins.
The first example shows the case that pure HTML code runs well.

A. What you type:

this is the first line <br/> this is the <strong> second </strong> line 

A. What you see:

The following examples show the use of the HTML plugin.

B. What you type:

<<< HTML
  <span style="padding: 10px; border: 1px solid blue; ">
     span with padding; this item is **not bold**
  </span> 
>>>

B. What you see:

C. What you type:

<<< HTML
  <hr style="background-color: red; height: 10px;" /> <!-- RED RULE --> 
>>>

C. What you see:

D. What you type:

<<< HTML
<table class="table_creole" >
    <tr>
        <th>Heading Col 1</th>
        <th>Heading Col 2</th>
    </tr>
    <tr>
        <td>Cell 1.1</td>
        <td>Two lines<br />in Cell 1.2</td>
    </tr>
    <tr>
        <td>Cell 2.1</td>
        <td>Cell 2.2</td>
    </tr>
</table>
>>>

D. What you see:

E. What you type:

<<< HTML <div style="border: 1px solid blue;" >  >>>
# Item 1
## Item 1.1
## Item 1.2
# Item 2

<<< HTML </div> >>>

E. What you see:

ADDITIONS TO CREOLE 1.0

      Additional inline elements

      Indented Paragraphs

A. What you type:

:this is indented  \\\ second indented line  

A. What you see:

A. HTML code:

<div style="margin-left: 2em">
   <p> this is indented  <br /> second indented line 
   </p>
</div>

B. What you type:

This is a normal paragraph.  \\\ 
:This is an indented         \\\ 
paragraph in two lines.      \\\ 
::This is more indented.

B. What you see:

B. HTML code:

<p> This is a normal paragraph.  <br /> </p>
<div style="margin-left: 2em">
  <p> This is an indented  <br /> 
      paragraph in two lines.  <br /> 
  </p>
  <div style="margin-left: 2em">
     <p> This is more indented.
     </p>
  </div>
</div>

      Definition Lists

What you type:

; Title 1
: Item 1.1 : Item 1.2
; Title 2 : Item 2.1 \\\ Item 2.2  \\\  Item 2.3

What you see:

HTML code:

<dl>
  <dt>Title 1</dt>
    <dd></dd>
    <dd>Item 1.1</dd>
    <dd>Item 1.2</dd>
  <dt>Title 2 </dt>
    <dd>Item 2.1 <br /> Item 2.2  <br />  Item 2.3</dd>
</dl>

      Plugins

Creole 1.0 Additions supports two plugin syntaxes:

1. << plugin content >>
2. <<< plugin content >>>

The Perl module Text::WikiCreole not only converts Creole to XHTML but also enables the user to add its own plugins. With Txt2Site the following plugins are supported:

1. Invisible anchor.

Syntax

ANCHOR <name>

Description

Inserts an invisible anchor. HTML code <a name="name" > </a>

Can be used to link to a location on a page.

Use [[ #name | Linkname ]] to create a link to the location of the anchor.

2. Linebreak.

In Creole linebreaks can be forced by \\\ .
An alternative syntax for forcing a linebreak is with this plugin.

Syntax

BR

Description

Inserts a linebreak. HTML code <br/>

3. Numbering.

Numbering macro: supports simple numbering.

Syntax

# <number>

Description

Returns a number maintained by the system. The argument is optional. If applied, set the number to the given value. If no argument applied, the number is increased by one. The scope of the numbering is a content section.
For example << # 5 >> resets the number to 5 and displays it. Each call << # >> increments the number by one and displays it.

4. Colored text.

Syntax

COLOR <colorname> <words>

Description

Inserts the words with the given color. Use HTML colornames or HTML colorcodes (like #700). Creole syntax of words is not interpreted. Creates a HTML span element.

Example

Type this << COLOR RED This is red text >> to get this This is red text

5. Print spaces.

Syntax

SPACES <count>

Description

Inserts <count> number of spaces. Uses &nbsp; to print a space.

6. Insert HTML code.

Syntax

HTML <lines of html-code>

Description

Inserts one of more lines of html-code. In fact inserts the given text literally. No interpretation by the Creole parser. See the section Using HTML for examples.